# Kernel compilation and update

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# Overview

This document describes the complete process of compiling the Linux kernel for Quectel Pi H1, packaging kernel images, and updating them to the device. Quectel Pi H1 uses a Yocto-based build system with a Qualcomm-customized Linux kernel (based on Linux 6.6).

# Kernel recipes description

Qualcomm Linux kernel recipes are located in the `/layers/meta-qcom-hwe/recipes-kernel/linux` directory. This layer provides two kernel solutions:

| **Recipe File** | **Kernel Type** | **Source** | **Description** |
| --- | --- | --- | --- |
| linux-qcom-custom_6.6.bb | Custom BSP | git.codelinaro.org | Qualcomm-customized kernel (currently used) |
| linux-qcom-base_6.6.bb | Base BSP | git.kernel.org | Standard kernel |

> **Currently used**: Custom kernel source solution

# Directory structure

Kernel-related files are divided into two directories:

```plaintext
qcm6490-idp/
├── kernel-source/               # Kernel source directory
└── kernel-build-artifacts/      # Build artifacts directory
```

## Kernel-source/ Directory

This directory stores the complete source code of the Linux kernel, including:

- Kernel core code (`arch/`, `drivers/`, `fs/`, `net/`, etc.)

- Device tree source files (`.dts`/`.dtsi`, describing hardware configurations)

- Kernel configuration files (`Kconfig`)

- Build scripts (`Makefile`)

### Source directory details

```{image} images/image_II2sbxmQKoZ8ZpxjGAVcqMBWnnh.webp
:width: 1238px
:height: 59px
```

| **Directory/File** | **Description** | **Directory/File** | **Description** |
| --- | --- | --- | --- |
| arch | Architecture-related code (ARM64, x86, etc.) | scripts | Compilation and configuration scripts |
| block | Block device subsystem | security | Security framework (SELinux, AppArmor, etc.) |
| certs | Kernel certificates and signatures | sound | Audio subsystem (ALSA) |
| crypto | Encryption API and algorithms | tools | Kernel-related tools |
| Documentation | Kernel documentation | usr | initramfs generation related |
| drivers | Device drivers | virt | Virtualization support (KVM) |
| fs | File system implementation | rust | Rust language support |
| include | Kernel header files | Makefile | Main configuration file |
| init | Kernel initialization code | Kbuild | Kernel build system configuration |
| ipc | Inter-process communication mechanisms | Kconfig | Kernel configuration interface definition |
| kernel | Kernel core functionalities (scheduler, process management, etc.) | MAINTAINERS | Maintainer list |
| lib | Common library functions | CREDITS | Contributor list |
| mm | Memory management subsystem | COPYING | Copyright notice (GPL) |
| net | Network protocol stack |   |   |
| samples | Kernel programming example code |   |   |

## Kernel-build-artifacts/ Directory

This directory stores kernel build artifacts after compilation, including:

- **Kernel image files**: `Image` (uncompressed) or `Image.gz` (compressed version)

- **Device tree binary files**: `.dtb` files (compiled from `.dts`)

- **Kernel modules**: `.ko` files (loadable driver modules)

- **Configuration files**: `.config`, `build.log`, etc.

# Compile kernel

## Configure build environment

Enter the code working directory and execute the following command to configure the build environment:

```bash
source quectel_build/compile/build.sh
```

## Execute compilation

Use Yocto's `bitbake` command to compile the kernel:

```bash
bitbake linux-qcom-custom
```

## Build artifact paths

After compilation is complete, the kernel image is generated at the following location:

**Temporary working directory**:

```plaintext
build-qcom-wayland/tmp-glibc/work/qcm6490_idp-qcom-linux/linux-qcom-custom/6.6/deploy-linux-qcom-custom
```

**Final deployment directory** (automatically copied by Yocto):

```plaintext
build-qcom-wayland/tmp-glibc/deploy/images/qcm6490-idp/
```

```{image} images/image_Ta7Pb2CnuoYavxxuRDrczD2wnkd.webp
:width: 1362px
:height: 108px
```

> **Note**: Yocto will automatically copy the kernel image from the working directory to the deployment directory. During the subsequent packaging process, the kernel image is obtained from the deployment directory.

## Build time reference

- **First build**: Approximately 30–60 minutes (depending on hardware configurations)

- **Incremental build**: Approximately 5–15 minutes

# Package kernel and device tree images

## Install ukify tool

First, install the Python dependencies required for packaging:

```bash
sudo pip install pefile
```

## Execute packaging command

Run the following command to package the kernel image and device tree:

```bash
do_kernel_images
```

## ukify warning description

During the packaging process, the following warning messages will appear, which **can be ignored**:

```bash
Kernel version not specified, starting autodetection .
Real-Mode Kernel Header magic not found
+ readelf --notes {TOPDIR}/quectel_build/alpha/tools/pack/image_temp/Image
readelf: Error: Not an ELF file - it has the wrong magic bytes at the start
Found uname version: 6.6.52-qli-1.3-ver.1.1
Wrote unsigned ${TOPDIR}/quectel_build/alpha/tools/pack/image_temp/uki.efi
```

> **Note**: These warnings are caused by differences between ARM64 kernel format and EFI tool expected format, and do not affect the correctness of the final image.

## Get packaged image

After packaging is complete, obtain the generated image file from the following path:

```plaintext
${TOPDIR}/quectel_build/alpha/output/pack/efi.bin
```

# Update image to device

## Method 1: Enter Fastboot via debug UART

### Enter Fastboot mode

**Option A - Via serial port command**:

Connect the debug UART and execute in the system:

```bash
reboot bootloader
```

**Option B - Via ADB command**:

Ensure the device is connected via USB and ADB debugging is enabled, then execute:

```bash
adb shell
reboot bootloader
```

### Verify Fastboot mode

After the device enters Fastboot mode, run on the host:

```bash
fastboot devices
```

Now you can see the device list.

### Flash kernel image

Use the fastboot command to flash the new kernel image:

```bash
fastboot flash efi efi.bin
```

### Reboot device

After flashing is complete, reboot the device:

```bash
fastboot reboot
```

## Method 2: Automation script (optional)

If you need to frequently update the kernel, you can create an automation script:

```bash
#!/bin/bash# update_kernel.sh# Check if efi.bin existsif [ ! -f "quectel_build/alpha/output/pack/efi.bin" ]; thenecho "Error: efi.bin does not exist, please compile and package the kernel first."exit 1fi# Enter Fastboot
adb reboot bootloader
sleep 5# Wait for Fastboot to be ready
fastboot devices

# Flash image
fastboot flash efi quectel_build/alpha/output/pack/efi.bin

# Reboot
fastboot rebootecho "Kernel update complete!"
```

Usage:

```bash
chmod +x update_kernel.sh
./update_kernel.sh
```

# Notes

1. **Backup important data**: Before updating the kernel, ensure important data is backed up.

2. **Sufficient power**: Ensure the device has sufficient power or is connected to power during flashing.

3. **Stable USB connection**: Use a good quality USB cable to avoid flashing interruption.

4. **Version matching**: Ensure the kernel version is compatible with other system components.

# FAQs

## Q1: bitbake compilation failed?

**Possible causes**:

- Insufficient disk space

- Network connection problems

- Missing dependency packages

**Solution**:

```bash
# Clean build cache
bitbake -c cleanall linux-qcom-custom
# Recompile
bitbake linux-qcom-custom
```

## Q2: Device cannot be seen after Fastboot mode is verified?

**Solution**:

- Check if USB drivers are correctly installed

- Try changing USB port or cable

- Confirm the device has correctly entered Fastboot mode (screen displays Fastboot text)

## Q3: Cannot boot after flashing?

**Solution**:

- Use factory image to restore the system

- Check if there were errors during compilation

- Confirm device tree configuration is correct

# Related documents

- [Device tree file description](<../Device tree file description/Device tree file description.md>)

- [Cross-Compilation toolchain](<../Cross-Compilation toolchain/Cross-Compilation toolchain.md>)